<html id="classes-tutorial" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Classes-introduction</title>
</head>

<body>

<h1>Introduction to Classes and Object Oriented Programming</h1>
<h2><a name="basics">Introduction</a></h2>
<todo>
References to other chapters that deal with classes.
</todo>
<p>LZX is an object-oriented, proto-type based language that allows you to create custom, reusable classes to streamline and minimize code.</p>

<p> This tutorial shows you how to define and instantiate classes, as well as where to use them. 
The <tagname>class</tagname> tag is used to define classes. Classes are instantiated when the tag is used.</p>

<example title="Simple Class Example">
&lt;canvas width="500" height="80"&gt;
  &lt;class name="MyClass" width="80" height="25" bgcolor="#CFD9AB"&gt;
    &lt;text align="center" valign="middle"&gt;Hello, World!&lt;/text&gt;
  &lt;/class&gt;
  
  &lt;MyClass name="myFirstInstance"/&gt;
&lt;/canvas&gt;
</example>

<p>The <tagname>class</tagname> tag defined the class, and the <tagname link="false">MyClass</tagname> tag <i>instantiated</i> it. 
Everything that was in the definition of the class is <i>inherited</i> by each instance of it that is created.
That is, the instance of MyClass inherits a width of 80, a height of 25, a background color, as well as some text. 
The instance is named "myFirstInstance", in the same way we might name a <tagname>view</tagname>, or 
a <tagname library="lz">window</tagname>.</p>

<p>In fact, when we write <tagname library="lz">window</tagname>, we are actually <i>instantiating</i> the window class, 
which is a pre-defined class.</p>

<p>In this example, there is only one element within the class (the <tagname>text</tagname> element). But classes can contain many objects;
for example, views can contain many subviews. </p>
<h4>The id attribute</h4>
<p>
It's important to note that you should not give an <attribute tagname="node">id</attribute> attribute 
to the subview of a class, as ids are global and creating several instances of a class will create several views with the same id.</p>
<todo>
What the above is saying is that instances, not classes, should get IDs.  What happens otherwise?
</todo>


<h2><a name="inheritance"></a>Inheritance</h2>

<p>As mentioned above, instances of <tagname link="false">MyClass</tagname> are going to inherit from it. Just because we 
didn't specify <attribute tagname="view">x</attribute> and <attribute tagname="view">y</attribute> coordinates in the class definition doesn't mean we can't give them to the instance:</p>

<p>The <tagname>class</tagname> tag defined the class, and the <tagname link="false">MyClass</tagname> tag <i>instantiated</i> it. Everything that was in the definition of the class is <i>inherited</i> by the instance of it that we have created. i.e. The instance of <tagname>MyClass</tagname> inherits a width of 80, a height of 25, a background color, as well as some text. The instance is named "myFirstInstance", in the same way we might name a view, or a <tagname library="lz">window</tagname>.</p>

<p>The instances behave just like views. In fact, that's because we are <i>extending</i> the view class. By default, the <tagname>class</tagname> tag extends the view class, so:</p>

<pre>&lt;class name="MyClass"&gt;</pre>

<p>&#x2026; is the same as&#x2026;</p>

<pre>&lt;class name="MyClass" <em>extends="view"</em>&gt;</pre>

<p>It follows that you can extend any class you want:</p>
<example title="Extending the 'button' class">
&lt;canvas width="500" height="80"&gt;
  &lt;class name="SpecialButton" extends="button" onclick="changeLabel()"&gt;
    &lt;method name="changeLabel"&gt;
      this.setAttribute('text', 'Clicked! ');
    &lt;/method&gt;
  &lt;/class&gt;
  
  &lt;SpecialButton&gt;Not clicked&lt;/SpecialButton&gt;
&lt;/canvas&gt;
</example>

<p>Since the <tagname>button</tagname> can take a text childnode that becomes its label, the <tagname link="false">SpecialButton</tagname> class 
that extends it can also take the text childnode. The method <method>changeLabel</method> is also inherited by the instance.</p>

<p>Just as with attributes, methods can be overwritten in instances:</p>

<example title="Overwriting methods'">
&lt;canvas width="500" height="80"&gt;
  &lt;class name="SpecialButton" extends="button" onclick="changeLabel()"&gt;
    &lt;method name="changeLabel"&gt;
      this.setAttribute('text', 'Clicked!');
    &lt;/method&gt;
  &lt;/class&gt;
  
  &lt;simplelayout axis="y" spacing="10"/&gt;
  &lt;SpecialButton&gt;Not clicked&lt;/SpecialButton&gt;
  &lt;SpecialButton&gt;
    Click Me Now
    <em>&lt;method name="changeLabel"&gt;
      this.setAttribute('text', 'Smashing!');
    &lt;/method&gt;</em>
  &lt;/SpecialButton&gt;
&lt;/canvas&gt;
</example>

<p>Rewriting methods can be very handy when using both your own and pre-defined classes components, 
but it's not practical for when you have a class for which every instance may need a particular argument. </p>


<h2><a name="attributes"></a>Attributes</h2>

<p>We've used attributes before (e.g. width="160"), but these have been attributes that are present in the class we are extending. 
As mentioned above, it is useful to be able to pass an instance of a class an argument when it is created:</p>


<example title="Passing an argument to class instance">
&lt;canvas width="500" height="80"&gt;
  &lt;class name="SpecialButton" extends="button" onclick="changeLabel()"&gt;
    &lt;attribute name="changeToLabel" value="Clicked!" type="string"/&gt;
    &lt;method name="changeLabel"&gt;
      var newLabel = this.getAttribute('changeToLabel');
      this.setAttribute('text', newLabel);
    &lt;/method&gt;
  &lt;/class&gt;
  
  &lt;simplelayout axis="y" spacing="10"/&gt;
  &lt;SpecialButton&gt;Not clicked&lt;/SpecialButton&gt;
  &lt;SpecialButton <em>changeToLabel="Thank You!"</em>&gt;Please click me!&lt;/SpecialButton&gt;
&lt;/canvas&gt;
</example>

<p>If we give the attribute a value, then that will be its default value, and will get assigned if we don't explicitly set it.</p>

<h2>More Inheritance</h2>

<p>You can extend a class more than once. For example, an application might contain more than one kind of button:</p>

<ul>
  <li>A standard button that is blue, then switches to green when we roll over it. This button writes the name of a pet out.</li>
  <li>A special button, that is red, but also switches to green when we roll over it. This button writes out a day of the week.</li>
</ul>


<example title="Extending class more than once">
&lt;canvas width="800" height="300" debug="true"&gt;
  &lt;debug x="175"/&gt;
  &lt;resource name="standardButton"&gt;
    &lt;frame src="../resources/button_blue.gif"/&gt;
    &lt;frame src="../resources/button_green.gif"/&gt;
  &lt;/resource&gt;
  
  &lt;resource name="specialButton"&gt;
    &lt;frame src="../resources/button_blue.gif"/&gt;
    &lt;frame src="../resources/button_red.gif"/&gt;
  &lt;/resource&gt;
  
  &lt;class name="MyButton" resource="standardButton" 
         onclick="doAction()" onmouseover="doOver()" onmouseout="doOut()"&gt;
    &lt;method name="doAction"&gt;
      Debug.write('Dog');
    &lt;/method&gt;
    &lt;method name="doOver"&gt;
      this.setResourceNumber(2);
    &lt;/method&gt;
    &lt;method name="doOut"&gt;
      this.setResourceNumber(1);
    &lt;/method&gt;
  &lt;/class&gt;
  
  &lt;class name="MySpecialButton" <em>extends="MyButton"</em> resource="specialButton"&gt;
    &lt;method name="doAction"&gt;
      Debug.write('Monday');
    &lt;/method&gt;
  &lt;/class&gt;
  
  &lt;view name="buttons" x="125" y="5"&gt;
    &lt;simplelayout axis="y" spacing="10"/&gt;
    <em>&lt;MyButton/&gt;
    &lt;MySpecialButton/&gt;</em>
  &lt;/view&gt;
&lt;/canvas&gt;
</example>

<p>Here we only changed the <method>doAction</method> method and the resource. The <method>doOver</method> and <method>doOut</method> methods remained the same, so there was no need to redefine them in the MySpecialButton definition.</p>



<h2><a name="placing"></a>Placing views inside of classes</h2>

<p>Since we frequently write classes that extend view, at some stage we're going to need to place a view inside an instance of a class that we have created. For example, we may want to write a window class and put a text field inside of its title bar. Or we may want to put some content inside the middle of our window. There are two ways to do this: giving the subviews <attribute tagname="node">placement</attribute> attributes, or giving the class the <attribute tagname="class">defaultplacement</attribute> attribute.</p>

<h3>Placing views using the placement attribute</h3>
<p>If you had one view and you specifically wanted to place it in a particular subview of a class, you would use the <attribute tagname="node">placement</attribute> attribute of that view. </p>

<p>An example is the title bar of a window: It's unlikely that you would need to place several things in the title bar of a window, so it's OK to have to add the <attribute tagname="node">placement</attribute> attribute to the subview of the class that you want to place in the title bar.</p>


<h3>Placing views by defining class with a defaultplacement attribute</h3>
<todo>
Link to other chapters where this is described
</todo>
<p>If you want every subview of a class to be placed in the same location, then you give the <i>class definition</i> a defaultplacement attribute.</p>

<p>An example is the contents of a window class. If you built your own window class (see the window tutorial), you might well have an area for all window content. You might well place numerous subviews in that window, and you don't want to explicitly position <i>each</i> one.</p>
<todo>
conclusion and link to next subjects.
</todo>


</body>
</html>
<!-- * X_LZ_COPYRIGHT_BEGIN ***************************************************
* Copyright 2001-2004 Laszlo Systems, Inc.  All Rights Reserved.              *
* Use is subject to license terms.                                            *
* X_LZ_COPYRIGHT_END ****************************************************** -->
